Skip to content

feat(worktrees): suspend and resume scripts for minimized tasks - #376

Open
gnutix wants to merge 1 commit into
johannesjo:mainfrom
gnutix:fix/worktree-suspend-resume
Open

gnutix wants to merge 1 commit into
johannesjo:mainfrom
gnutix:fix/worktree-suspend-resume

Conversation

@gnutix

@gnutix gnutix commented Nov 15, 2026

Copy link
Copy Markdown

What and why

Minimizing a task ("Minimize (stop agents)", or a snooze that stops agents) stops its agents, but whatever the task's worktree started keeps running. With a docker compose stack per worktree (an app server, a frontend, a database, a cache), twenty-odd minimized tasks kept that many stacks up: tens of GB of RAM and swap for tasks nobody was working on. Only closing a task stops them, through the Teardown script, and closing also removes the worktree.

This adds two optional per-project scripts next to Setup and Teardown (#349), under Project settings → Tasks → Worktree setup:

  • Suspend script: runs in the worktree when a task is minimized, or snoozed with its agents stopped, after the agents stop (e.g. docker compose stop). Snoozing a task that keeps its agents running does not run it: those agents may still need the services.
  • Resume script: runs when that task is restored (e.g. docker compose start). The task is marked suspended when its suspend script runs, and the mark is persisted, so a restore after a restart resumes only tasks that were suspended. A task minimized before the scripts were set up is left as it was.

They follow the Teardown script's design: headless on the host, in the worktree, with PARALLEL_CODE_ROOT_PATH, PARALLEL_CODE_WORKTREE, PARALLEL_CODE_BRANCH and the project's env vars, two minutes at most, and only in a folder git worktree list reports for the repository. Neither holds up the minimize or the restore: the layout changes at once, and a failure is announced in a notification naming the task, with the last lines of output. A project with neither set behaves exactly as before.

Scripts on one worktree now run one at a time, in the order asked, so a quick minimize-and-restore resumes only after the suspend finished, and closing a task right after minimizing it tears down after the suspend.

Implementation:

  • electron/ipc/worktree-scripts.ts: runTeardownScript becomes runWorktreeScript (with a per-worktree queue), and describeWorktreeScriptFailure takes the script's label. Teardown behaviour is unchanged.
  • One new channel, RunWorktreeLifecycleScript (manifest and preload allowlist), validated like DeleteTask's teardown fields.
  • collapseTask / uncollapseTask send the scripts; Task.worktreeSuspended is persisted for minimized tasks.
  • Settings fields, persistence sanitising and docs/features.md.

They run for every task with a worktree, imported ones and archived sub-tasks included, but not for tasks on the current branch.

How I checked it

  • npm run check, npm run check:static and npm test pass.
  • New tests:
    • runner: scripts of one worktree run in order even when the first is slow, and a failure notice carries the label
    • IPC: suspend then resume sent back to back run in that order with the variables and project env; a failing suspend comes back as a warning, not an error; invalid kind, script and path are refused before anything runs
    • store: suspend runs after the agents are killed with the task's worktree, branch and project; resume runs on restore and clears the mark; neither blocks the layout change; failures and refused runs are announced naming the task; no resume for a task that was never suspended; nothing without a suspend script, nothing for a task on the current branch; the mark is cleared when the project has no resume script
    • snooze: a snooze that stops agents suspends and resumes when it returns; a snooze that keeps them runs neither
    • persistence round trip of the mark and the two project scripts; updateProject; the settings dialog saves both fields
  • Ran a suspend script (docker compose -p <project> stop for the worktree's stack) and resume script against real compose stacks: stopped on suspend, started on resume, volumes kept.
  • Not verified in the packaged app: the notification and the minimize/restore flow end to end.

Screenshots

Project settings → Tasks → Worktree setup, with a setup and a teardown script set.

Before After
Before After
Setup and Teardown only. Suspend script and Resume script below Teardown, with their hints.

Agent use

Claude Code wrote and tested this change.

🤖 Generated with Claude Code (Opus 5.5)

Minimizing a task stops its agents but leaves running whatever its
worktree started, such as a docker compose stack per worktree. With
many tasks set aside, those stacks hold memory until each task is
closed, and only closing runs the teardown script, which also removes
the worktree.

Two optional per-project scripts sit next to Setup and Teardown under
Project settings → Tasks → Worktree setup:

- Suspend script: runs in the worktree when a task is minimized, or
  snoozed with its agents stopped, after the agents stop. Snoozing with
  agents running does not run it.
- Resume script: runs when that task is restored. A task is marked
  suspended when the script runs, and the mark is persisted, so a
  restore after a restart resumes only tasks that were suspended.

Both run headless like teardown, with the same variables, project env
and two-minute limit, and only in a folder git lists as a worktree of
the repository. Neither holds up the minimize or restore; a failure is
announced in a notification naming the task. Scripts on one worktree
now run one at a time in the order asked, so a quick restore resumes
after the suspend finished, and a close right after a minimize tears
down after it.

The headless runner is renamed from runTeardownScript to
runWorktreeScript, and its failure notice takes the script's label.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant